WIDGET_INFO

The WIDGET_INFO function is used to obtain information about the widget subsystem and individual widgets. The specific area for which information is desired is selected by setting the appropriate keyword.

Syntax

Result = WIDGET_INFO( [Widget_ID] )

Keywords that apply to all widgets: [, / ACTIVE] [, /ALL_CHILDREN] [, /CHILD] [, /DISPLAY] [, /EVENT_FUNC] [, /EVENT_PRO] [, FIND_BY_UNAME=string] [, /FONTNAME] [, /FUNC_GET_VALUE] [, /GEOMETRY] [, /KBRD_FOCUS_EVENTS] [, /MANAGED] [, /MAP] [, /N_CHILDREN] [, /NAME] [, /PARENT] [, /PRO_SET_VALUE] [, /REALIZED] [, /SENSITIVE] [, /SIBLING] [, STRING_SIZE={string | [string, font]}] [, /SYSTEM_COLORS] [, /TAB_MODE] [, /TRACKING_EVENTS] [, /TYPE] [, UNITS={0 | 1 | 2}] [, /UNAME] [, /UPDATE] [, /VALID_ID] [, /VERSION] [, /VISIBLE]

Keywords that apply to WIDGET_BASE: [, /CONTEXT_EVENTS] [, /MODAL] [, /TLB_ICONIFY_EVENTS] [, /TLB_KILL_REQUEST_EVENTS] [, /TLB_MOVE_EVENTS] [, /TLB_SIZE_EVENTS]

Keywords that apply to WIDGET_BROWSER: [, /BROWSER_CAN_GO_BACK] [, /BROWSER_CAN_GO_FORWARD] [, /BROWSER_GET_PAGE_SOURCE]

Keywords that apply to WIDGET_BUTTON: [, /BUTTON_SET] [, /DYNAMIC_RESIZE] [, /MASK] [, /PUSHBUTTON_EVENTS] [, /TOOLTIP]

Keywords that apply to WIDGET_COMBOBOX: [, /COMBOBOX_GETTEXT] [, /COMBOBOX_NUMBER] [, /DYNAMIC_RESIZE] [, /LIST_EVENTS]

Keywords that apply to WIDGET_DRAW and WIDGET_WINDOW: [, /DRAG_NOTIFY] [, /DRAW_BUTTON_EVENTS] [, /DRAW_EXPOSE_EVENTS] [, DRAW_KEYBOARD_EVENTS={0 | 1 | 2}] [, /DRAW_MOTION_EVENTS] [, /DRAW_VIEWPORT_EVENTS] [, /DRAW_WHEEL_EVENTS] [, /DROP_EVENTS] [, /TOOLTIP]

Keywords that apply to WIDGET_DROPLIST: [, /DROPLIST_NUMBER] [, /DROPLIST_SELECT] [, /DYNAMIC_RESIZE]

Keywords that apply to WIDGET_LABEL: [, /DYNAMIC_RESIZE]

Keywords that apply to WIDGET_LIST: [, /CONTEXT_EVENTS] [, /LIST_MULTIPLE] [, /LIST_NUMBER] [, /LIST_NUM_VISIBLE] [, /LIST_SELECT] [, /LIST_TOP]

Keywords that apply to WIDGET_PROPERTYSHEET: [, /CONTEXT_EVENTS] [, COMPONENT=objref] [, /MULTIPLE_PROPERTIES] [, PROPERTY_VALID=string] [, PROPERTY_VALUE=string] [, /PROPERTYSHEET_NSELECTED] [, /PROPERTYSHEET_SELECTED]

Keywords that apply to WIDGET_SLIDER: [, /SLIDER_MIN_MAX]

Keywords that apply to WIDGET_TAB: [, /TAB_CURRENT] [, /TAB_MULTILINE] [, /TAB_NUMBER]

Keywords that apply to WIDGET_TABLE: [, /COLUMN_WIDTHS] [, /CONTEXT_EVENTS] [, /ROW_HEIGHTS] [, /TABLE_ALL_EVENTS] [, /TABLE_BACKGROUND_COLOR] [, /TABLE_DISJOINT_SELECTION] [, /TABLE_EDITABLE] [, /TABLE_EDIT_CELL] [, /TABLE_FONT] [. /TABLE_FOREGROUND_COLOR] [, /TABLE_SELECT] [, /TABLE_VIEW] [, /TEXT_SELECT] [, /USE_TABLE_SELECT]

Keywords that apply to WIDGET_TEXT: [, /CONTEXT_EVENTS] [, /TEXT_ALL_EVENTS] [, /TEXT_EDITABLE] [, /TEXT_NUMBER] [, TEXT_OFFSET_TO_XY=integer] [, /TEXT_SELECT] [, /TEXT_TOP_LINE] [, TEXT_XY_TO_OFFSET=[column, line]]

Keywords that apply to WIDGET_TREE: [, /CONTEXT_EVENTS] [, /DRAG_NOTIFY] [, /DRAGGABLE] [, /DROP_EVENTS] [, /MASK] [, /TOOLTIP] [, /TREE_BITMAP] [, /TREE_CHECKBOX] [, /TREE_CHECKED] [, /TREE_DRAG_SELECT] [, /TREE_EXPANDED] [, /TREE_FOLDER] [, /TREE_INDEX] [, /TREE_ROOT] [, /TREE_SELECT]

Return Value

Returns the specified information for the given widget ID or the WIDGET_SYSTEM_COLORS Structure if the SYSTEM_COLORS keyword is specified.

Arguments

Widget_ID

Usually this argument should be the widget ID of the widget for which information is desired. If the ACTIVE or VERSION keywords are specified, this argument is not required.

Widget_ID can also be an array of widget identifiers, in which case the result is an array with the same structure in which information on all the specified widgets is returned.

Keywords

Not all keywords to WIDGET_INFO apply to all combinations of widgets. In the following list, descriptions of keywords that affect only certain types of widgets include a list of the widgets for which the keyword is useful.

ACTIVE

This keyword applies to all widgets.

Set this keyword to return 1 if there is at least one realized, managed, top-level widget on the screen. Otherwise, 0 is returned.

ALL_CHILDREN

This keyword applies to all widget types.

Set this keyword to have the widget system return an array that contains the widget IDs of the given widget's immediate children. A scalar is returned if the widget contains only one child. If the widget does not have any children then the return value is the scalar value 0 (zero). When there are multiple children, the returned array is ordered according to the position of the children. This keyword can only be applied to one widget at a time. The N_CHILDREN keyword complements ALL_CHILDREN.

Note: If the widget possesses a context menu then the returned array will include the context base. Widget types can be discovered using the TYPE and NAME keywords to WIDGET_INFO.

BROWSER_CAN_GO_BACK

This keyword applies to widgets created with the WIDGET_BROWSER function.

If this keyword is set then WIDGET_INFO will return 1 or 0, indicating whether the browser has a prior page that can be navigated to or not.

BROWSER_CAN_GO_FORWARD

This keyword applies to widgets created with the WIDGET_BROWSER function.

If this keyword is set then WIDGET_INFO will return 1 or 0, indicating whether the browser has a next page that can be navigated to or not.

BROWSER_GET_PAGE_SOURCE

This keyword applies to widgets created with the WIDGET_BROWSER function.

If this keyword is set then WIDGET_INFO will return a string array containing the HTML source code of the current browser page.

BUTTON_SET

This keyword applies to widgets created with the WIDGET_BUTTON function.

Set this keyword to return the “set” state of a widget button. If the button is currently set, 1 (one) is returned. If the button is currently not set, 0 (zero) is returned. This keyword is intended for use with exclusive, non-exclusive and checked menu buttons.

CHILD

This keyword applies to all widgets.

Set this keyword to return the widget ID of the first child of the widget specified by Widget_ID. If the widget has no children, 0 is returned.

COLUMN_WIDTHS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return an array of long integers giving the width of each column in the table. If USE_TABLE_SELECT is set equal to one, only the column widths for columns that contain currently-selected cells are returned. If USE_TABLE_SELECT is set equal to an array, only the column widths for columns that contain specified cells are returned.

COMBOBOX_GETTEXT

This keyword applies to widgets created with the WIDGET_COMBOBOX function.

Set this keyword to return the current text from the text box of the specified combobox widget. Note that when using an editable combobox, the text displayed in the text box may not be an item from the list of values in the combobox list. To obtain the index of the selected item, inspect the INDEX field of the event structure returned by the combobox widget.

COMBOBOX_NUMBER

This keyword applies to widgets created with the WIDGET_COMBOBOX function.

Set this keyword to return the number of elements currently contained in the list of the specified combobox widget.

COMPONENT

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to an object reference to indicate which object to query. This is most useful when the property sheet references multiple objects. If this keyword is not specified, the first (possibly only) object is queried.

CONTEXT_EVENTS

This keyword applies to widgets created with the WIDGET_BASE, WIDGET_LIST, WIDGET_PROPERTYSHEET, WIDGET_TABLE, WIDGET_TEXT or WIDGET_TREE functions.

Set this keyword to determine whether the widget specified by Widget_ID is configured to generate context events (that is, the widget was created with the CONTEXT_EVENTS keyword set). The return value is 1 (one) if context events will be generated, or 0 (zero) otherwise.

DISPLAY

This keyword applies to all widgets.

Set this keyword to return True (1) if IDL is running in an environment capable of displaying widgets, or False (0) otherwise. Windows always returns True. On Unix, False will be returned when IDL's DISPLAY environment variable does not specify a display with a running or valid X server.

Use this keyword to determine whether IDL is running in a headless environment.

DRAG_NOTIFY

This keyword applies to widgets created with the WIDGET_DRAW,WIDGET_TREE, and WIDGET_WINDOW functions.

Set this keyword to retrieve the name of the drag notification callback. If the widget is using the default callback, the return value will be the string <default> (including the < and > characters). If the widget is using the callback of its parent node, the return value will be the string <inherit> (including the < and > characters). When inheriting, the name of the callback that is ultimately invoked can be discovered by walking up the tree widget hierarchy until <inherit> is not returned. For more details, see the DRAG_NOTIFY keyword of WIDGET_DRAW, WIDGET_TREE and WIDGET_WINDOW.

DRAGGABLE

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to determine whether the tree widget is draggable. Possible return values are:

1

The widget is draggable because the DRAGGABLE keyword was set when the widget was created.

0

The widget is not draggable because the DRAGGABLE keyword was explicitly set to 0 when the widget was created.

-1

The widget inherits the draggability setting of its parent. To determine the actual draggability of the widget, you must walk up the widget hierarchy until an ancestor of the selected widget returns 1 or 0.

Although it is never draggable, the root node of a tree widget can set DRAGGABLE to 1 or 0 so that its children can inherit the value. WIDGET_INFO will return the current setting.

DRAW_BUTTON_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return 1 if Widget_ID is a draw widget with the BUTTON_EVENTS attribute set. Otherwise, 0 is returned.

DRAW_EXPOSE_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return 1 if Widget_ID is a draw widget with the EXPOSE_EVENTS attribute set. Otherwise, 0 is returned.

DRAW_KEYBOARD_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return an integer specifying the type of keyboard events currently generated by the draw widget specified by Widget_ID. Possible values are:

Note: Keyboard events are never generated for function keys.

DRAW_MOTION_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return 1 if Widget_ID is a draw widget with the MOTION_EVENTS attribute set. Otherwise, 0 is returned.

DRAW_VIEWPORT_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return 1 if Widget_ID is a draw widget with the VIEWPORT_EVENTS attribute set. Otherwise, 0 is returned.

DRAW_WHEEL_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

If this keyword is set and the provided widget ID is for a draw widget, WIDGET_INFO returns True (1) if mouse wheel events are enabled for the given draw widget and False (0) if wheel events are disabled. WIDGET_INFO also returns False if this keyword is used on non-draw widgets.

DROP_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW, WIDGET_TREE and WIDGET_WINDOW functions.

Set this keyword to determine whether or not a widget generates drop events.

Possible return values are:

1

The widget will generate drop events because the DROP_EVENTS keyword was set when the widget was created.

0

The widget will not generate drop events because the DROP_EVENTS keyword was explicitly set to 0 when the widget was created.

-1

The widget inherits the DROP_EVENTS setting of its parent. To determine whether a widget that reports -1 will generate drop events, you must walk up the widget hierarchy until an ancestor of the selected widget returns 1 or 0.

Widgets can generate drop events regardless of whether or not a drag notification callback has been specified (explicitly or inherited implicitly).

DROPLIST_NUMBER

This keyword applies to widgets created with the WIDGET_DROPLIST function.

Set this keyword to return the number of elements currently contained in the specified droplist widget.

DROPLIST_SELECT

This keyword applies to widgets created with the WIDGET_DROPLIST function.

Set this keyword to return the zero-based number of the currently-selected element (i.e., the currently-displayed element) in the specified droplist widget.

DYNAMIC_RESIZE

This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_COMBOBOX, WIDGET_DROPLIST, and WIDGET_LABEL functions.

Set this keyword to return a True value (1) if the widget specified by Widget_ID is a button, droplist, or label widget that has had its DYNAMIC_RESIZE attribute set. Otherwise, False (0) is returned.

EVENT_FUNC

This keyword applies to all widgets.

Set this keyword to return a string containing the name of the event handler function associated with Widget_ID. An empty string is returned if no event handler function exists.

EVENT_PRO

This keyword applies to all widgets.

Set this keyword to return a string containing the name of the event handler procedure associated with Widget_ID. An empty string is returned if no event handler procedure exists.

FIND_BY_UNAME

This keyword applies to all widgets.

Set this keyword to a UNAME value that will be searched for in the widget hierarchy, and if a widget with the given UNAME is in the hierarchy, its ID is returned. The search starts in the hierarchy with the given widget ID and travels down, and this keyword returns the widget ID of the first widget that has the specified UNAME value.

If a widget is not found, 0 is returned.

FONTNAME

This keyword applies to all widgets that support fonts. If the specified widget does not support fonts, WIDGET_INFO returns an empty string.

Note: The WIDGET_BASE, WIDGET_DRAW, WIDGET_TAB, and WIDGET_TREE widgets do not support fonts.

Set this keyword to return a string containing the name of the font being used by the specified widget. The returned name can then be used when creating other widgets.

Note: If the widget being queried has not yet been realized, this keyword will return the default font even if another font has been specified. To ensure that you are retrieving the correct font, query for the font name after realizing the widget.

You can use this keyword to retrieve the name of the default font used by one type of widget and use the same font in other contexts. For example, the following code retrieves the default font used for buttons and writes into the drawable area of a draw widget using the same font:

wBase = WIDGET_BASE(/ROW)

wButton = WIDGET_BUTTON(wBase, VALUE="Button")

wDraw = WIDGET_DRAW(wBase, XSIZE=200, YSIZE=100)

WIDGET_CONTROL, wBase, /REALIZE

strFont = WIDGET_INFO(wButton, /FONTNAME)

DEVICE, SET_FONT=strFont

WIDGET_CONTROL, wDraw, GET_VALUE=iWindow

WSET, iWindow

XYOUTS, 100, 50, 'Same Font as Button', FONT=0, /DEVICE, $

   ALIGNMENT=.5

This method allows you to synchronize the fonts in several widgets without knowing in advance which font is in use.

The format of the returned font name is platform dependent. See Using Device Fonts for additional details.

FUNC_GET_VALUE

This keyword applies to all widgets.

Set this keyword to return a string containing the name of the FUNC_GET_VALUE function associated with Widget_ID. An empty string is returned if no FUNC_GET_VALUE function exists.

GEOMETRY

This keyword applies to all widgets.

Note: Some widgets have no geometry values of their own. For example, only the root node of a tree widget hierarchy has associated geometry values. Similarly, buttons created on a pop-up menu have no geometry. Widgets with no intrinsic geometry values will return a WIDGET_GEOMETRY structure containing all zeroes.

Set this keyword to return a WIDGET_GEOMETRY structure that describes the offset and size information for the widget specified by Widget_ID. This structure has the following definition:

{ WIDGET_GEOMETRY,

   XOFFSET:0.0,

   YOFFSET:0.0,

   XSIZE:0.0,

   YSIZE:0.0,

   SCR_XSIZE:0.0,

   SCR_YSIZE:0.0,

   DRAW_XSIZE:0.0,

   DRAW_YSIZE:0.0,

   MARGIN:0.0,

   XPAD:0.0,

   YPAD:0.0,

   SPACE:0.0 }

With the exception of MARGIN, all of the structure’s fields correspond to the keywords of the same name to the various widget routines. MARGIN is the width of any frame added to the widget, in units specified by the UNITS keyword (pixels are the default). Therefore, the actual width of any widget is:

SCR_XSIZE + (2* MARGIN)

The actual height of any widget is:

SCR_YSIZE + (2 * MARGIN)

Note: Different window managers may use different window dressing (borders, margins, scrollbars, etc.). As a result, running a given segment of widget code on different platforms may yield different geometry.

Note: In most cases, setting SCR_XSIZE (or SCR_YSIZE) for a base widget should override the value set via the XSIZE (or YSIZE) keyword. For unrealized base widgets on Microsoft Windows platforms, however, the returned WIDGET_GEOMETRY structure will report the specified value of XSIZE (or YSIZE) rather than the value supplied via the SCR_XSIZE (or SCR_YSIZE) keyword.

Note: For table widgets, the YSIZE and XSIZE values return the total number of rows and columns, which may differ from the visible number of rows and columns.

KBRD_FOCUS_EVENTS

This keyword applies to all widgets.

Set this keyword to return the keyboard focus events status of the widget specified by Widget ID. WIDGET_INFO returns 1 (one) if keyboard focus events are currently enabled for the widget, or 0 (zero) if they are not. Only base, table, and text widgets can generate keyboard focus events.

LIST_EVENTS

When this keyword is set, events are generated when the dropdown list is navigated by arrow up and arrow down keys.

LIST_MULTIPLE

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword equal to a named variable that will contain a non-zero value if the list widget supports multiple item selections. See the MULTIPLE keyword to WIDGET_LIST for more on multiple item selections.

LIST_NUMBER

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to return the number of elements currently contained in the specified list widget.

LIST_NUM_VISIBLE

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to return the number of elements that can be visible in the scrolling viewport of the specified list widget. Note that this value can be larger than the total number of elements actually in the list.

LIST_SELECT

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to return the index or indices of the currently selected (highlighted) element or elements in the specified list widget. Note that this offset is zero-based. If no element is currently selected, -1 is returned.

LIST_TOP

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to return the zero-based offset of the topmost element currently visible in the specified list widget.

MANAGED

This keyword applies to all widgets.

Set this keyword to return 1 if the specified widget is managed, or 0 otherwise. If no widget ID is specified in the call to WIDGET_INFO, the return value will be an array containing the widget IDs of all currently-managed widgets.

MAP

This keyword applies to all widgets.

Set this keyword to return True (1) if the widget specified by Widget_ID is mapped (visible), or False (0) otherwise. Note that when a base widget is unmapped, all of its children are unmapped. If WIDGET_INFO reports that a particular widget is unmapped, it may be because a parent in the widget hierarchy has been unmapped.

MASK

This keyword applies to widgets created with the WIDGET_BUTTON and WIDGET_TREE functions.

Set this keyword to determine whether a widget’s bitmap makes use of transparency. The return value will be 1 if the bitmap uses transparency, or 0 otherwise. The tree root node and nodes that use the default icon always return 1. For more information, see the MASK keywords to WIDGET_BUTTON and WIDGET_TREE.

MODAL

This keyword applies to widgets created with the WIDGET_BASE function and the MODAL keyword.

If this keyword is set, WIDGET_INFO will return True (1) if the base widget specified by Widget_ID is a modal base widget, or False (0) otherwise.

MULTIPLE_PROPERTIES

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to return the property sheet’s current selection mode. A value of 1 indicates support for multiple property selection. A value of 0 indicates that only single property selection is permitted.

N_CHILDREN

This keyword applies to all widget types.

Set this keyword to return the number of children that belong to a widget. This keyword complements the ALL_CHILDREN keyword.

Note: If the widget possesses a context menu then the count will include the context base.

NAME

This keyword applies to all widgets.

Set this keyword to return the widget type name of the widget specified by Widget_ID. The returned value will be one of the following strings: “BASE”, “BUTTON”, “COMBOBOX”, “DRAW”, “DROPLIST”, “LABEL”, “LIST”, “PROPERTYSHEET”, “SLIDER”, “TAB”, “TABLE”, “TEXT”, or “TREE”. Set the TYPE keyword to return the widget’s type code.

PARENT

This keyword applies to all widgets.

Set this keyword to return the widget ID of the parent of the widget specified by Widget_ID. If the widget is a top-level base (i.e., it has no parent), 0 is returned.

PRO_SET_VALUE

This keyword applies to all widgets.

Set this keyword to return a string containing the name of the PRO_SET_VALUE procedure associated with Widget_ID. An empty string is returned if no PRO_SET_VALUE procedure exists.

PROPERTY_VALID

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to a scalar string or one-element string array that contains a property identifier. If the specified property is included in the property sheet, WIDGET_INFO will return 1; if the property is not included in the property sheet, WIDGET_INFO will return 0. Comparisons are case-insensitive.

Note: Property identifiers returned in the IDENTIFIER field of an event structure generated by a property sheet widget can be assumed to be valid.

PROPERTY_VALUE

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to a string that contains a property identifier. If the specified property is included in the property sheet, WIDGET_INFO will return the value of the property. If the specified property is not included in the property sheet, WIDGET_INFO will generate an error; use the PROPERTY_VALID keyword to WIDGET_INFO to check for validity before retrieving the property value. Comparisons are case-insensitive.

If the property sheet contains multiple components, use the COMPONENT keyword to indicate which component the property value should be retrieved from.

Note on use of this keyword

When a user changes a value in the property sheet widget, the actual value of the underlying property does not change automatically. Use this keyword to retrieve the value specified by the user, then apply the new value to the underlying component. The following code snippet illustrates this process:

PRO prop_event, e

 

; Get the value of the changed property, using the component and

; property identifier information contained in the widget event.

value = WIDGET_INFO( e.id, COMPONENT = e.component, $

   PROPERTY_VALUE = e.identifier )

 

; Set the component's property's value

e.component->SetPropertyByIdentifier, e.identifier, value

 

END

PROPERTYSHEET_NSELECTED

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to return the number of currently selected properties. The COMPONENT keyword is not required.

PROPERTYSHEET_SELECTED

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to return the identifiers of the currently selected properties. The return value depends on the number of rows selected as follows:

Selection

Return Value

No Properties Selected

Returns an empty string (' ').

Single Property Selected

Returns a string containing the property identifier.

Multiple Properties Selected

Returns an array of strings containing each selected property’s identifier.

The COMPONENT keyword is not required.

PUSHBUTTON_EVENTS

This keyword applies to widgets created with the WIDGET_BUTTON function.

Set this keyword to return the pushbutton events status for the widget specified by Widget_ID. WIDGET_INFO returns 1 if pushbutton events are currently enabled for the widget, or 0 otherwise.

REALIZED

This keyword applies to all widgets.

Set this keyword to return 1 if the widget specified by Widget_ID has been realized. If the widget has not been realized, 0 is returned.

ROW_HEIGHTS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return an array of floating-point values giving the height of each row in the table. If USE_TABLE_SELECT is set equal to one, only the row heights for rows that contain currently selected cells are returned. If USE_TABLE_SELECT is set equal to an array, only the row heights for rows that contain specified cells are returned.

Note: On Microsoft Windows platforms, all value rows have the same height, but the column header can have a distinct height. The column header is indexed by a value of -1 for the row.

SENSITIVE

This keyword applies to all widgets.

Set this keyword to return true (1) if the widget specified by Widget_ID is sensitive (enabled), or false (0) otherwise. Note that when a base is made insensitive, all its children are made insensitive. If WIDGET_INFO reports that a particular widget is insensitive, it may be because a parent in the widget hierarchy has been made insensitive.

SIBLING

This keyword applies to all widgets.

Set this keyword to return the widget ID of the first sibling of the widget specified by Widget_ID. If the widget is the last sibling in the chain, 0 is returned.

SLIDER_MIN_MAX

This keyword applies to widgets created with the WIDGET_SLIDER function.

Set this keyword to return the current minimum and maximum values of the specified slider as a two-element integer array. Element 0 is the minimum value and element 1 is the maximum value.

STRING_SIZE

This keyword applies to all widget types.

Set this keyword to retrieve the dimensions of a string. The return value is a two-element vector containing the string’s width and height in pixels. A widget identifier must always be specified in the call. The keyword’s value can be either the measured string or a two-element vector containing first the string and then a font. If a font is specified, that font is used in the calculations. Otherwise, the widget’s font is used. In the case of a table widget with multiple fonts, the default font is used. See Using Device Fonts for details on specifying names for device fonts.

Note: When you are using the dimensions returned by this keyword, take into account the padding that a widget uses around a string. STRING_SIZE returns the exact dimensions, which if used can cut off the string’s edges.

Note: This keyword’s height results might not be 100% reliable from calculation of the specified font’s overall size. The calculation uses the span between the maximum ascender and descender in the font’s catalogue, regardless of whether those letters appear in the specified string being measured.

SYSTEM_COLORS

This keyword applies to all widgets.

Set this keyword and supply the widget ID of any widget to cause WIDGET_INFO to return an IDL structure that contains RGB values used for 25 IDL display elements.

For more detailed information on the WIDGET_SYSTEM_COLORS structure fields and their meaning see the WIDGET_SYSTEM_COLORS Structure.

TAB_CURRENT

This keyword applies to widgets created with the WIDGET_TAB function.

Set this keyword to return the zero-based index of the current tab in the tab widget.

TAB_MODE

This keyword applies to all widgets.

Set this keyword to return what support the specified widget has for navigating among widgets using the Tab key. Possible return values are:

0

Navigation is not supported onto or off of the widget

1

Navigation is supported onto and off of the widget

2

Navigation is supported only onto the widget

3

Navigation is supported only off of the widget

Note: In widget applications on the UNIX platform, the Motif library controls what widgets are brought into and released from focus using tabbing. The TAB_MODE keyword value is always zero, and any attempt to change it is ignored when running a widget application on the UNIX platform. Tabbing behavior may vary significantly between UNIX platforms; do not rely on a particular behavior being duplicated on all UNIX systems.

TAB_MULTILINE

This keyword applies to widgets created with the WIDGET_TAB function.

Set this keyword to return the current setting of the multi-line mode for the tab widget.

TAB_NUMBER

This keyword applies to widgets created with the WIDGET_TAB function.

Set this keyword to return the number of tabs contained in the tab widget.

TABLE_ALL_EVENTS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return 1 (one) if Widget_ID is a table widget with the ALL_EVENTS attribute set. Otherwise, 0 (zero) is returned.

TABLE_BACKGROUND_COLOR

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return the background colors of table cells. Colors are returned as RGB triplets, where each byte for red, green, and blue is in the range [0,255]. Normally all of the table's cells are queried, but you can indicate a subset with the USE_TABLE_SELECT keyword. If all of the colors are identical, the return value is a three-element vector of bytes (an RGB triplet). If any one color is different, the return value has all of the colors in an array whose dimensions mirror the query set specification.

Note: On systems that do not support a large number of colors, the color value returned by WIDGET_INFO may not match the value specified via WIDGET_TABLE or WIDGET_CONTROL exactly. The value returned by WIDGET_INFO is the color that was actually applied.

For more information on the return value, see Table Widget Cell Attributes.

TABLE_DISJOINT_SELECTION

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return 1 (one) if the widget specified by Widget_ID has disjoint selection enabled. Otherwise, 0 (zero) is returned.

TABLE_EDITABLE

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return the editability of table cells. Values are returned as single bytes containing 0 (not editable) or 1 (editable). Normally all of the table's cells are queried, but you can indicate a subset with the USE_TABLE_SELECT keyword. If all of the values are identical, the return value is a scalar byte. If any one value is different, the return value has all of the values in an array whose dimensions mirror the query set specification.

For more information on the return value, see Table Widget Cell Attributes.

Note: When using a table with mixed editability, it is important that you take care when using the return value from TABLE_EDITABLE in a conditional because the value might not be scalar.

TABLE_EDIT_CELL

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return a two-element integer array containing the row and column coordinates of the currently editable cell. If none of the cells in the table widget is currently editable, the array [-1, -1] is returned.

TABLE_FONT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return the font names of table cells. Values are returned as strings. Normally all of the table's cells are queried, but you can indicate a subset with the USE_TABLE_SELECT keyword. If all of the font names are identical, the return value is a scalar string. If any one font is different, the return value has all of the values in an array whose dimensions mirror the query set specification.

For more information on the return value, see Table Widget Cell Attributes.

Note: On Microsoft Windows platforms, the returned font description is functionally equivalent to the originally specified font, but might have modifiers in a different order.

TABLE_FOREGROUND_COLOR

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return the text colors of table cells. Colors are returned as RGB triplets, where each byte for red, green, and blue is in the range [0,255]. Normally all of the table's cells are queried, but you can indicate a subset with the USE_TABLE_SELECT keyword. If all of the colors are identical, the return value is a three-element vector of bytes (an RGB triplet). If any one color is different, the return value has all of the colors in an array whose dimensions mirror the query set specification.

Note: On systems that do not support a large number of colors, the color value returned by WIDGET_INFO may not match the value specified via WIDGET_TABLE or WIDGET_CONTROL exactly. The value returned by WIDGET_INFO is the color that was actually applied.

For more information on the return value, see Table Widget Cell Attributes.

TABLE_SELECT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return the currently-selected (highlighted) cells in the specified table widget.

TABLE_VIEW

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return a two-element array of the form [left, top] containing the zero-based offsets of the top-left cell currently visible in the specified table widget.

TEXT_ALL_EVENTS

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return 1 if Widget_ID is a text widget with the ALL_EVENTS attribute set. Otherwise, 0 is returned.

TEXT_EDITABLE

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return 1 if Widget_ID is a text widget that allows user editing of its contents. Otherwise, 0 is returned.

TEXT_NUMBER

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return the number of characters currently contained in the specified text widget, including end-of-line characters.

Note: On Windows platforms, Carriage Return/Line Feed pairs count as a single character.

TEXT_OFFSET_TO_XY

This keyword applies to widgets created with the WIDGET_TEXT function.

Use this keyword to translate a text widget character offset into column and line form. The value of this keyword should be set to the character offset (an integer) to be translated. WIDGET_INFO returns a two-element integer array giving the column (element 0) and line (element 1) corresponding to the offset. If the offset specified is out of range, the array [-1,-1] is returned.

TEXT_SELECT

This keyword applies to widgets created with the WIDGET_TABLE and WIDGET_TEXT functions.

Set this keyword to return the starting character offset and length (in characters) of the selected (highlighted) text in the specified text widget or table cell. WIDGET_INFO returns a two-element integer array containing the starting position of the highlighted text as an offset from character zero of the text in the text widget or table cell (element 0), and length of the current selection (element 1).

TEXT_TOP_LINE

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return the zero-based line number of the line currently at the top of a text widget’s display viewport. Note that this value is different from the zero-based character offset of the characters in the line. The character offset can be calculated from the line offset via the TEXT_XY_TO_OFFSET keyword.

TEXT_XY_TO_OFFSET

This keyword applies to widgets created with the WIDGET_TEXT function.

Use this keyword to translate a text widget position given in line and column form into a character offset. The value of this keyword should be set to a two-element integer array specifying the column (element 0) and line (element 1) position. WIDGET_INFO returns the character offset (as a longword integer) corresponding to the position. If the position specified is out of range, -1 is returned.

TLB_ICONIFY_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to return 1 if the top-level base widget specified by Widget_ID is set to return iconify events. Otherwise, 0 is returned.

TLB_KILL_REQUEST_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to return 1 if the top-level base widget specified by Widget_ID is set to return kill request events. Otherwise, 0 is returned.

TLB_MOVE_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to return 1 if the top-level base widget specified by Widget_ID is set to return move events. Otherwise, 0 is returned.

TLB_SIZE_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to return 1 if the top-level base widget specified by Widget_ID is set to return resize events. Otherwise, 0 is returned.

TOOLTIP

This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_DRAW, WIDGET_TREE, and WIDGET_WINDOW functions.

Set this keyword to have the WIDGET_INFO function return the text of the tooltip of the widget. If the widget does not have a tooltip, an empty string will be returned.

TRACKING_EVENTS

This keyword applies to all widgets.

Set this keyword to return the tracking events status for the widget specified by Widget_ID. WIDGET_INFO returns 1 if tracking events are currently enabled for the widget. Otherwise, 0 is returned.

TREE_BITMAP

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return an MxNx3 array containing the RGB image or an MxNx4 array representing an RGBA image specified as the tree widget node’s bitmap. If the node uses the default bitmap or is a tree root, then scalar zero is returned. This keyword can only be applied to one widget at a time.

TREE_CHECKBOX

This keyword applies to widgets created with the WIDGET_TREE function, using the CHECKBOX keyword. Set this keyword to return whether or not a node has a checkbox. A value of 1 indicates that a checkbox exists. A value of zero indicates no checkbox.

TREE_CHECKED

This keyword applies to widgets created with the WIDGET_TREE function, using the CHECKBOX and CHECKED keywords. Set this keyword to return the checked state of a node. Possible return values are:

Value

Description

0

Not checked

1

Checked

2

Mixed state

TREE_DRAG_SELECT

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return a modified selection list that does not include nodes that have a selected ancestor. This is useful when an application automatically copies or moves a selected folder’s children, as does the WIDGET_TREE_MOVE routine.

There are two modes of operation, depending on the widget ID passed to WIDGET_INFO:

By providing the “pruned” list of nodes to the copy or move routine, an application that automatically copies or moves all of a selected node’s children will avoid copying or moving both the parent and then, later, any selected children. If you use the WIDGET_TREE_MOVE routine, use this keyword when retrieving the list of selected nodes.

Use TREE_SELECT to retrieve the full list of selected nodes.

TREE_EXPANDED

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return 1 (one) if the specified tree widget node is a folder that is expanded, or 0 (zero) if the specified node is a folder that is collapsed.

Note: Only tree widget nodes created with the FOLDER keyword can be expanded or collapsed. This keyword will always return 0 (zero) if the specified tree widget node is not a folder.

TREE_FOLDER

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to determine if a tree widget node is a folder or leaf node. The root and folders result in a return value of 1 (one) and leaf nodes return 0 (zero).

TREE_INDEX

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return the position of the specified tree widget. The return value is the zero-based index of the widget relative to its siblings.

TREE_ROOT

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return the widget ID of the root node of the tree widget hierarchy of which Widget ID is a part. The root node is the tree widget whose parent is a base widget.

TREE_SELECT

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return information about the nodes selected in the specified tree widget. This keyword has two modes of operation, depending on the widget ID passed to WIDGET_INFO:

This keyword returns the exact list of selected nodes. If you are passing the list of nodes to a routine that moves or copies selected nodes, consider using the TREE_DRAG_SELECT keyword instead.

TYPE

This keyword applies to all widgets.

Set this keyword to return the type code of the specified Widget_ID. Possible values are given the following table. Note that you can set the NAME keyword to return string names instead.

Value

Type

0

Base

1

Button

2

Slider

3

Text

4

Draw

5

Label

6

List

8

Droplist

9

Table

10

Tab

11

Tree

12

Combobox

13

Property sheet

UNAME

This keyword applies to all widgets.

Set this keyword to have the WIDGET_INFO function return the user name of the widget.

UNITS

This keyword applies to all widgets.

Set this keyword to specify the units used when returning measurements or position values for most widget types. Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. This keyword does not change the units used in a widget event structure or in most of the fields of the geometry structure returned by WIDGET_INFO.

Note: This keyword does not affect all sizing operations. Specifically, the value of UNITS is ignored when retrieving the XSIZE or YSIZE of a WIDGET_LIST, WIDGET_TABLE, or WIDGET_TEXT functions.

UPDATE

This keyword applies to all widgets.

Set this keyword to return 1 if the widget hierarchy that contains Widget_ID is set to display updates. Otherwise, 0 is returned. See "UPDATE.

USE_TABLE_SELECT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to modify the behavior of the COLUMN_WIDTHS, ROW_HEIGHTS, TABLE_BACKGROUND_COLOR, TABLE_EDITABLE, TABLE_FONT, and TABLE_FOREGROUND_COLOR keywords. If USE_TABLE_SELECT is set, these keywords apply only to the currently selected cells. If USE_TABLE_SELECT is not set, these keywords apply to the entire contents of a table widget.

The USE_TABLE_SELECT keyword can be specified as an array of coordinates (disjoint selection mode) or as a four-element array of the form [left, top, right, bottom] (standard selection mode), giving the group of cells to act on. You can specify header cells by using -1 in the appropriate index: row header cells use -1 for the column, and column header cells use -1 for the row. Ranges can span header and value cells.

VALID_ID

This keyword applies to all widgets.

Set this keyword to return 1 if Widget_ID represents a currently valid widget. Otherwise, 0 is returned.

VERSION

This keyword applies to all widgets.

Set this keyword to return a structure that gives information about the widget implementation. This structure has the following definition:

{ WIDGET_VERSION, STYLE:'', TOOLKIT:'', RELEASE:'' }

STYLE is the style of widget toolkit used. TOOLKIT is the implementation of the toolkit. RELEASE is the version level of the toolkit. This field can be used to distinguish between different releases of a given toolkit, such as Motif 1.0 and Motif 1.1.

VISIBLE

This keyword applies to all widgets.

Set this keyword to return True (1) if the widget specified by Widget_ID is visible, or False (0) otherwise. A widget is visible if:

Note: The value returned by WIDGET_INFO when this keyword is set is not affected if the widget is minimized or obscured by another window. Widgets that are visible in the sense of this keyword may not be immediately apparent to a person viewing a particular display device.

The WIDGET_SYSTEM_COLORS Structure

When the SYSTEM_COLORS keyword is specified in a call to WIDGET_INFO, IDL returns a WIDGET_SYSTEM_COLORS structure. This allows application developers to determine what colors are used in IDL application widgets, so they can design widgets for their application with the same look and feel as the supplied IDL widgets.

The WIDGET_SYSTEM_COLORS structure consists of 25 fields, each containing a three-element vector corresponding to the Red, Green, and Blue color values used for various widget elements. The vector elements are integers ranging between 0 and 255 if a color value is available (vector elements contain –1 if the color value is unavailable). The field names and meaning on the Windows and UNIX operating systems are shown in the following table.

Field Names

Windows Platform

UNIX Platform

DARK_SHADOW_3D

Dark shadow color for 3D display elements.

N/A

FACE_3D

Face color for 3D display elements and dialog boxes.

Base background color for all widgets.

LIGHT_EDGE_3D

Highlight color for 3D edges that face the light source.

Color of top and left edges of 3D widgets.

LIGHT_3D

Light color for 3D display elements.

Color of highlight rectangle around widgets with the keyboard focus.

SHADOW_3D

Color for 3D edges that face away from the light source.

Color of bottom and right edges of 3D widgets.

ACTIVE_BORDER

Active window’s border color.

Push button background color when button is armed.

ACTIVE_CAPTION

Active window’s caption color.

N/A

APP_WORKSPACE

Background color of MDI applications.

N/A

DESKTOP

Desktop color.

N/A

BUTTON_TEXT

Text color on push buttons.

Widget text color.

CAPTION_TEXT

Color of text in caption, size box, and scroll bar arrow box.

Widget text color.

GRAY_TEXT

Color of disabled text.

N/A

HIGHLIGHT

Color of item(s) selected in a widget.

Toggle button fill color.

HIGHLIGHT_TEXT

Color of text of item(s) selected in a widget.

N/A

INACTIVE_BORDER

Inactive window’s border color.

N/A

INACTIVE_CAPTION

Inactive window’s caption color.

N/A

INACTIVE_CAPTION_TEXT

Inactive window’s caption text color.

N/A

TOOLTIP_BK

Background color for tooltip controls.

N/A

TOOLTIP_TEXT

Text color for tooltip controls.

N/A

MENU

Menu background color.

N/A

MENU_TEXT

Menu text color.

N/A

SCROLLBAR

Color of scroll bar “gray” area.

Color of scroll bar “gray” area.

WINDOW_BK

Window background color.

Base background color for all widgets.

WINDOW_FRAME

Window frame color.

Widget border color.

WINDOW_TEXT

Text color in windows.

Widget text color.

Version History

Pre-4.0

Introduced

5.6

Added BUTTON_SET, COMBOBOX_GETTEXT, COMBOBOX_NUMBER, FONTNAME, MAP, SENSITIVE, TAB_CURRENT, TAB_MULTILINE, TAB_NUMBER, TABLE_DISJOINT_SELECTION, TLB_ICONIFY_EVENTS, TLB_MOVE_EVENTS, TLB_SIZE_EVENTS, TOOLTIP, TREE_EXPANDED, TREE_ROOT, TREE_SELECT, and VISIBLE keywords

6.0

Added COMPONENT, PROPERTY_VALID, PROPERTY_VALUE, and PUSHBUTTON_EVENTS keywords

6.1

Added MULTIPLE_PROPERTIES, PROPERTYSHEET_NSELECTED, PROPERTYSHEET_SELECTED, TAB_MODE keywords

6.2

Added DRAW_WHEEL_EVENTS, STRING_SIZE, TABLE_BACKGROUND_COLOR, TABLE_FONT, and TABLE_FOREGROUND_COLOR keywords

6.3

Added DRAG_NOTIFY, DRAGGABLE, DROP_EVENTS, TREE_BITMAP, TREE_FOLDER, TREE_INDEX, ALL_CHILDREN, N_CHILDREN, MASK, and TREE_DRAG_SELECT keywords

8.2

Modified the MASK keyword to include WIDGET_BUTTON

Added TREE_CHECKBOX and TREE_CHECKED keywords

8.2.1

Added LIST_EVENTS keyword
8.7.2 Added BROWSER_CAN_GO_BACK, BROWSER_CAN_GO_FORWARD

See Also

WIDGET_CONTROL, About Widgets